NPM Package Security Scanning Utilities

This repository contains two PowerShell Core scripts designed for comprehensive npm package analysis and security scanning across multiple projects.

Overview

• Scan-NpmPackages.ps1: Scans directory trees for npm packages and generates detailed reports
• Scan-ReportsForPackages.ps1: Security scanner that identifies affected packages from watchlists

Prerequisites

• PowerShell Core 7.0 or later
• Windows, macOS, or Linux
• Projects with package.json and/or package-lock.json files

Scripts

1. Scan-NpmPackages.ps1

Scans directory structures for npm packages and creates comprehensive reports including all dependencies and transitive dependencies.

Key Features

• Scans package.json files for dependency information
• Processes package-lock.json files by default for complete dependency trees (1,600+ packages vs 50 direct dependencies)
• Supports all dependency types: regular, dev, peer, and optional
• Generates CSV reports with detailed package information
• Handles npm lock file formats v1, v2, and v3
• Warns when lock files are missing for optimal dependency analysis

Parameters

• Root (Required): Root directory to scan for npm projects
• OutDir: Output directory for reports (default: ./npm-package-report)
• SkipLockFiles: Skip lock files and use only package.json (not recommended)
• IncludeDev: Include devDependencies
• IncludePeer: Include peerDependencies
• IncludeOptional: Include optionalDependencies
• IncludeDependencyTree: Recursively scan dependency trees
• ShowVersionSpecs: Show version specifications instead of installed versions
• MaxDepth: Maximum recursion depth (default: 10)

Examples

# Basic scan of all projects under C:\repos (uses lock files by default)
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos"

# Comprehensive scan with all dependency types
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos" -IncludeDev -IncludePeer -IncludeOptional

# Scan with custom output directory
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos" -OutDir ".\reports"

# Deep dependency analysis with version specifications
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos" -IncludeDependencyTree -ShowVersionSpecs -MaxDepth 15

# Use only package.json files (skip lock files - not recommended)
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos" -SkipLockFiles -IncludeDev

Output Files

• packages_aggregate.csv: Summary of all unique packages across projects
• packages_detailed.csv: Detailed view with project locations and dependency types
• Individual project reports: project-name_packages.csv

2. Scan-ReportsForPackages.ps1

Security scanning tool that identifies affected packages from watchlists or vulnerability databases.

Key Features

• Reads CSV reports generated by Scan-NpmPackages.ps1
• Matches packages against security watchlists
• Supports multiple input methods: files, parameters, or pipeline
• Generates security-focused reports with affected package detection
• Handles version comparisons and mismatches
• Color-coded output for security assessment

Parameters

• ReportsDir (Required): Directory containing CSV reports from Scan-NpmPackages.ps1
• PackageList: Array of packages to check against
• PackageListFile: Path to file containing package watchlist
• AggregateReportFile: Name of aggregate report file (default: packages_aggregate.csv)
• DetailedReportFile: Name of detailed report file (default: packages_detailed.csv)
• OutputFile: Save results to CSV file
• ShowNotFound: Display watchlist packages not found in reports
• ShowVersionMismatches: Highlight version differences
• IncludeSecurityInfo: Include security context in output

Input Format

Watchlist entries can be provided in several formats:

• Simple package names: chalk
• With versions: chalk@5.3.0
• Tab-separated: chalk 5.3.0 High-risk package
• With descriptions: debug 4.4.2 CVE-2023-1234 vulnerability

Examples

# Scan reports for specific affected packages
.\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports" -PackageList @("chalk", "debug", "lodash")

# Use a security watchlist file
.\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports" -PackageListFile "security-watchlist.txt"

# Pipeline input for dynamic security scanning
$vulnerabilities = @(
    "chalk	5.3.0	High-risk package",
    "debug	4.4.2	CVE-2023-1234",
    "lodash	4.17.20	Security vulnerability"
)
$vulnerabilities | .\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports"

# Comprehensive security analysis with file output
.\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports" -PackageListFile "watchlist.txt" -ShowNotFound -ShowVersionMismatches -IncludeSecurityInfo -OutputFile "security-scan-results.csv"

# Quick check for specific packages with custom report names
.\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports" -PackageList @("express", "react") -AggregateReportFile "my-aggregate.csv" -DetailedReportFile "my-detailed.csv"

Complete Workflow Examples

Standard Security Scanning Workflow

# Step 1: Scan all projects for npm packages (lock files used by default)
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos" -OutDir ".\reports" -IncludeDev

# Step 2: Check against security watchlist
.\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports" -PackageListFile "security-watchlist.txt" -ShowNotFound -IncludeSecurityInfo -OutputFile "security-results.csv"

Comprehensive Enterprise Analysis

# Complete package analysis with all dependency types
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos" -OutDir ".\reports" -IncludeDev -IncludePeer -IncludeOptional -IncludeDependencyTree

# Security assessment with version mismatch analysis
.\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\reports" -PackageListFile "enterprise-watchlist.txt" -ShowNotFound -ShowVersionMismatches -IncludeSecurityInfo -OutputFile "enterprise-security-report.csv"

Quick Vulnerability Check

# Fast scan using lock files (default behavior)
.\scripts\Scan-NpmPackages.ps1 -Root "C:\repos"

# Check for specific CVEs
$cvePackages = @("debug	4.4.2	CVE-2023-1234", "chalk	5.3.0	CVE-2023-5678")
$cvePackages | .\scripts\Scan-ReportsForPackages.ps1 -ReportsDir ".\npm-package-report"

Sample Watchlist File Format

Create a security-watchlist.txt file with entries like:

chalk	5.3.0	High-risk package with security issues
debug	4.4.2	CVE-2023-1234 - Information disclosure
lodash	4.17.20	Multiple security vulnerabilities
express	4.18.0	Security advisory GHSA-xxx
axios	0.21.0	Server-side request forgery

Output Files

From Scan-NpmPackages.ps1

• packages_aggregate.csv: Unique packages with usage counts
• packages_detailed.csv: All package instances with project paths
• project-name_packages.csv: Individual project reports

From Scan-ReportsForPackages.ps1

• [OutputFile]: Affected packages detected in your projects
• [OutputFile]_not_detected.csv: Watchlist packages not found (good security posture)

Security Best Practices

1. Lock files are used by default for complete dependency analysis
2. Include all dependency types (-IncludeDev, -IncludePeer, -IncludeOptional)
3. Regularly update watchlists with latest security advisories
4. Monitor transitive dependencies as they represent the largest attack surface
5. Use version mismatch analysis to identify outdated packages
6. Save results to files for compliance and audit trails
7. Generate lock files if missing (npm install) for accurate analysis

Performance Tips

• Lock files are used by default for faster and more accurate results
• Limit -MaxDepth for very large projects
• Process reports in batches for large numbers of projects
• Use relative paths for portability across environments
• Use -SkipLockFiles only when necessary (reduces accuracy)

Troubleshooting

Common Issues

• Missing packages in results: Lock files are used by default for transitive dependencies
• Missing lock file warnings: Run npm install to generate package-lock.json files
• Performance issues: Reduce -MaxDepth or disable -IncludeDependencyTree
• File access errors: Run PowerShell as administrator if needed
• Encoding issues: Reports use UTF-8 encoding

Getting Help

Get-Help .\scripts\Scan-NpmPackages.ps1 -Full
Get-Help .\scripts\Scan-ReportsForPackages.ps1 -Full